# form_driver 3x

    form_driver(3x)                                         form_driver(3x)

## NAME

           form_driver - command-processing loop of the form system

## SYNOPSIS

           #include <form.h>
           int form_driver(FORM *form, int c);

## DESCRIPTION

           Once a form has been posted (displayed), you should funnel
           input events to it through form_driver.  This routine  has
           three major input cases:

           -  The  input  is  a  form navigation request.  Navigation
              request codes are constants defined in <form.h>,  which
              are distinct from the key- and character codes returned
              by wgetch.

           -  The input is a printable character.  Printable  charac-
              ters  (which  must  be  positive,  less  than  256) are
              checked according to the program's locale settings.

           -  The input is the KEY_MOUSE special key associated  with
              an mouse event.

           The form driver requests are as follows:

           REQ_NEXT_PAGE
                Move to the next page.

           REQ_PREV_PAGE
                Move to the previous page.

           REQ_FIRST_PAGE
                Move to the first page.

           REQ_LAST_PAGE
                Move to the last field.

           REQ_NEXT_FIELD
                Move to the next field.

           REQ_PREV_FIELD
                Move to the previous field.

           REQ_FIRST_FIELD
                Move to the first field.

           REQ_LAST_FIELD
                Move to the last field.

           REQ_SNEXT_FIELD
                Move to the sorted next field.

           REQ_SPREV_FIELD
                Move to the sorted previous field.

           REQ_SFIRST_FIELD
                Move to the sorted first field.

           REQ_SLAST_FIELD
                Move to the sorted last field.

           REQ_LEFT_FIELD
                Move left to a field.

           REQ_RIGHT_FIELD
                Move right to a field.

           REQ_UP_FIELD
                Move up to a field.

           REQ_DOWN_FIELD
                Move down to a field.

           REQ_NEXT_CHAR
                Move to the next char.

           REQ_PREV_CHAR
                Move to the previous char.

           REQ_NEXT_LINE
                Move to the next line.

           REQ_PREV_LINE
                Move to the previous line.

           REQ_NEXT_WORD
                Move to the next word.

           REQ_PREV_WORD
                Move to the previous word.

           REQ_BEG_FIELD
                Move to the beginning of the field.

           REQ_END_FIELD
                Move to the end of the field.

           REQ_BEG_LINE
                Move to the beginning of the line.

           REQ_END_LINE
                Move to the end of the line.

           REQ_LEFT_CHAR
                Move left in the field.

           REQ_RIGHT_CHAR
                Move right in the field.

           REQ_UP_CHAR
                Move up in the field.

           REQ_DOWN_CHAR
                Move down in the field.

           REQ_NEW_LINE
                Insert or overlay a new line.

           REQ_INS_CHAR
                Insert a blank at the cursor.

           REQ_INS_LINE
                Insert a blank line at the cursor.

           REQ_DEL_CHAR
                Delete character at the cursor.

           REQ_DEL_PREV
                Delete character before the cursor.

           REQ_DEL_LINE
                Delete line at the cursor.

           REQ_DEL_WORD
                Delete blank-delimited word at the cursor.

           REQ_CLR_EOL
                Clear to end of line from cursor.

           REQ_CLR_EOF
                Clear to end of field from cursor.

           REQ_CLR_FIELD
                Clear the entire field.

           REQ_OVL_MODE
                Enter overlay mode.

           REQ_INS_MODE
                Enter insert mode.

           REQ_SCR_FLINE
                Scroll the field forward a line.

           REQ_SCR_BLINE
                Scroll the field backward a line.

           REQ_SCR_FPAGE
                Scroll the field forward a page.

           REQ_SCR_BPAGE
                Scroll the field backward a page.

           REQ_SCR_FHPAGE
                Scroll the field forward half a page.

           REQ_SCR_BHPAGE
                Scroll the field backward half a page.

           REQ_SCR_FCHAR
                Scroll the field forward a character.

           REQ_SCR_BCHAR
                Scroll the field backward a character.

           REQ_SCR_HFLINE
                Horizontal scroll the field forward a line.

           REQ_SCR_HBLINE
                Horizontal scroll the field backward a line.

           REQ_SCR_HFHALF
                Horizontal scroll the field forward half a line.

           REQ_SCR_HBHALF
                Horizontal scroll the field backward half a line.

           REQ_VALIDATION
                Validate field.

           REQ_NEXT_CHOICE
                Display next field choice.

           REQ_PREV_CHOICE
                Display previous field choice.

           If  the  second  argument  is  a  printable character, the
           driver places it in the current position  in  the  current
           field.   If  it is one of the forms requests listed above,
           that request is executed.

       MOUSE HANDLING
           If the second argument is the KEY_MOUSE special  key,  the
           associated mouse event is translated into one of the above
           pre-defined requests.  Currently only clicks in  the  user
           window  (e.g.  inside the form display area or the decora-
           tion window) are handled.

           If you click above the display region of the form:

                  a REQ_PREV_FIELD is generated for a single click,

                  a REQ_PREV_PAGE is generated for a double-click and

                  a REQ_FIRST_FIELD is generated for a  triple-click.

           If you click below the display region of the form:

                  a REQ_NEXT_FIELD is generated for a single click,

                  a REQ_NEXT_PAGE is generated for a double-click and

                  a REQ_LAST_FIELD is generated for a triple-click.

           If you click at an field inside the display  area  of  the
           form:

                  -  the form cursor is positioned to that field.

                  -  If  you double-click a field, the form cursor is
                     positioned to that field  and  E_UNKNOWN_COMMAND
                     is  returned.   This  return  value makes sense,
                     because a double click  usually  means  that  an
                     field-specific action should be returned.  It is
                     exactly the purpose of this return value to sig-
                     nal  that an application specific command should
                     be executed.

                  -  If  a  translation  into  a  request  was  done,
                     form_driver  returns the result of this request.

           If you clicked outside the user window or the mouse  event
           could   not   be   translated   into  a  form  request  an
           E_REQUEST_DENIED is returned.

       APPLICATION-DEFINED COMMANDS
           If the second argument is neither printable nor one of the
           above  pre-defined form requests, the driver assumes it is
           an application-specific command and returns E_UNKNOWN_COM-
           MAND.  Application-defined commands should be defined rel-
           ative to MAX_COMMAND, the  maximum  value  of  these  pre-
           defined requests.

## RETURN VALUE

           form_driver returns one of the following error codes:

           E_OK The routine succeeded.

           E_BAD_ARGUMENT
                Routine  detected  an incorrect or out-of-range argu-
                ment.

           E_BAD_STATE
                Routine was called from an initialization or termina-
                tion function.

           E_NOT_POSTED
                The form has not been posted.

           E_INVALID_FIELD
                Contents of field is invalid.

           E_REQUEST_DENIED
                The form driver could not process the request.

           E_SYSTEM_ERROR
                System error occurred (see errno).

           E_UNKNOWN_COMMAND
                The form driver code saw an unknown request code.

## SEE ALSO

           curses(3x), form(3x), wgetch(3x).

## NOTES

           The header file <form.h> automatically includes the header
           files <curses.h>.

## PORTABILITY

           These routines emulate the System V forms  library.   They
           were not supported on Version 7 or BSD versions.

## AUTHORS

           Juergen  Pfeifer.   Manual  pages  and  adaptation for new
           curses by Eric S. Raymond.

                                                            form_driver(3x)